# Python 虚拟环境使用

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档说明 Quectel Pi M1/L1 上 Python 虚拟环境的基本使用方式。虚拟环境用于隔离项目依赖，避免第三方包影响系统 Python 环境。

# 环境确认

在开发板上先确认 Python 与系统环境：

```bash
python3 --version
cat /etc/os-release
command -v pip3 || echo "pip3 not installed"
```

| **项目** | **说明** |
| --- | --- |
| 系统 | 当前验证为 Debian GNU/Linux 13 (trixie) |
| Python | 当前验证为 Python 3.13.5 |
| pip3 | 当前镜像默认未检测到 pip3，按需安装 |

# 创建与启用

```bash
sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/projects/python-demo
cd ~/projects/python-demo
python3 -m venv .venv
source .venv/bin/activate
```

启用后可通过以下命令确认当前解释器和 pip 来自虚拟环境：

```bash
which python
which pip
python --version
pip --version
```

# 依赖管理

```bash
python -m pip install --upgrade pip
pip install <package_name>
pip freeze > requirements.txt
pip install -r requirements.txt
```

如项目需要 GPIO、串口或网络库，建议都安装在虚拟环境内。例如：

```bash
pip install pyserial requests python-periphery
```

# 退出环境

```bash
deactivate
```

# 注意事项

- `.venv` 目录通常不纳入版本控制。

- `requirements.txt` 建议随项目维护，便于多块开发板复现环境。

- Debian 13 上不建议默认使用 `--break-system-packages` 修改系统 Python 环境。